1   /*
2    * Copyright (C) 2006 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    * http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package com.google.common.util.concurrent;
18  
19  import com.google.common.annotations.Beta;
20  
21  import java.util.concurrent.Callable;
22  import java.util.concurrent.TimeUnit;
23  
24  /**
25   * Produces proxies that impose a time limit on method
26   * calls to the proxied object.  For example, to return the value of
27   * {@code target.someMethod()}, but substitute {@code DEFAULT_VALUE} if this
28   * method call takes over 50 ms, you can use this code:
29   * <pre>
30   *   TimeLimiter limiter = . . .;
31   *   TargetType proxy = limiter.newProxy(
32   *       target, TargetType.class, 50, TimeUnit.MILLISECONDS);
33   *   try {
34   *     return proxy.someMethod();
35   *   } catch (UncheckedTimeoutException e) {
36   *     return DEFAULT_VALUE;
37   *   }
38   * </pre>
39   * <p>Please see {@code SimpleTimeLimiterTest} for more usage examples.
40   *
41   * @author Kevin Bourrillion
42   * @since 1.0
43   */
44  @Beta
45  public interface TimeLimiter {
46  
47    /**
48     * Returns an instance of {@code interfaceType} that delegates all method
49     * calls to the {@code target} object, enforcing the specified time limit on
50     * each call.  This time-limited delegation is also performed for calls to
51     * {@link Object#equals}, {@link Object#hashCode}, and
52     * {@link Object#toString}.
53     * <p>
54     * If the target method call finishes before the limit is reached, the return
55     * value or exception is propagated to the caller exactly as-is. If, on the
56     * other hand, the time limit is reached, the proxy will attempt to abort the
57     * call to the target, and will throw an {@link UncheckedTimeoutException} to
58     * the caller.
59     * <p>
60     * It is important to note that the primary purpose of the proxy object is to
61     * return control to the caller when the timeout elapses; aborting the target
62     * method call is of secondary concern.  The particular nature and strength
63     * of the guarantees made by the proxy is implementation-dependent.  However,
64     * it is important that each of the methods on the target object behaves
65     * appropriately when its thread is interrupted.
66     *
67     * @param target the object to proxy
68     * @param interfaceType the interface you wish the returned proxy to
69     *     implement
70     * @param timeoutDuration with timeoutUnit, the maximum length of time that
71     *     callers are willing to wait on each method call to the proxy
72     * @param timeoutUnit with timeoutDuration, the maximum length of time that
73     *     callers are willing to wait on each method call to the proxy
74     * @return a time-limiting proxy
75     * @throws IllegalArgumentException if {@code interfaceType} is a regular
76     *     class, enum, or annotation type, rather than an interface
77     */
78    <T> T newProxy(T target, Class<T> interfaceType,
79        long timeoutDuration, TimeUnit timeoutUnit);
80  
81    /**
82     * Invokes a specified Callable, timing out after the specified time limit.
83     * If the target method call finished before the limit is reached, the return
84     * value or exception is propagated to the caller exactly as-is.  If, on the
85     * other hand, the time limit is reached, we attempt to abort the call to the
86     * target, and throw an {@link UncheckedTimeoutException} to the caller.
87     * <p>
88     * <b>Warning:</b> The future of this method is in doubt.  It may be nuked, or
89     * changed significantly.
90     *
91     * @param callable the Callable to execute
92     * @param timeoutDuration with timeoutUnit, the maximum length of time to wait
93     * @param timeoutUnit with timeoutDuration, the maximum length of time to wait
94     * @param interruptible whether to respond to thread interruption by aborting
95     *     the operation and throwing InterruptedException; if false, the
96     *     operation is allowed to complete or time out, and the current thread's
97     *     interrupt status is re-asserted.
98     * @return the result returned by the Callable
99     * @throws InterruptedException if {@code interruptible} is true and our
100    *     thread is interrupted during execution
101    * @throws UncheckedTimeoutException if the time limit is reached
102    * @throws Exception
103    */
104   <T> T callWithTimeout(Callable<T> callable, long timeoutDuration,
105       TimeUnit timeoutUnit, boolean interruptible) throws Exception;
106 }